---
type: integration
title: '@astrojs/alpinejs'
description: 了解如何使用 @astrojs/alpinejs 框架来在你的 Astro 项目中扩展组件支持。
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/alpinejs/'
category: renderer
i18nReady: true
---

import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'

这个 **[Astro 集成][astro-integration]** 将 [Alpine.js](https://alpinejs.dev/) 添加到你的项目中，这样你就可以在页面的任何位置使用 Alpine.js。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，可以改为[手动安装集成](#手动安装)。

要安装 `@astrojs/alpinejs`，请从项目目录中运行以下命令并按照提示进行操作：

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npx astro add alpinejs
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm astro add alpinejs
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn astro add alpinejs
    ```
  </Fragment>
</PackageManagerTabs>

如果遇到任何问题，[请随时在 GitHub 上向我们报告](https://github.com/withastro/astro/issues)，并尝试以下手动安装步骤。

### 手动安装

首先，安装 `@astrojs/alpinejs` 包。

<PackageManagerTabs>
  <Fragment slot="npm">
    ```sh
    npm install @astrojs/alpinejs
    ```
  </Fragment>
  <Fragment slot="pnpm">
    ```sh
    pnpm add @astrojs/alpinejs
    ```
  </Fragment>
  <Fragment slot="yarn">
    ```sh
    yarn add @astrojs/alpinejs
    ```
  </Fragment>
</PackageManagerTabs>

大多数包管理器会自动安装相关的 peer 依赖项。然而，如果在启动 Astro 时看到 "Cannot find package 'alpinejs'"（或者类似）的警告，则需要手动安装 Alpine.js：

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install alpinejs @types/alpinejs
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add alpinejs @types/alpinejs
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add alpinejs @types/alpinejs
  ```
  </Fragment>
</PackageManagerTabs>

然后，使用 `integrations` 属性将集成应用到你的 `astro.config.*` 文件中：

```js ins="alpine()" title="astro.config.mjs" ins={2}
import { defineConfig } from 'astro/config';
import alpine from '@astrojs/alpinejs';

export default defineConfig({
  // ...
  integrations: [alpine()],
});
```

## 配置选项

### `entrypoint`

请查阅我们的 [Astro 集成文档][astro-integration] 了解更多关于集成的信息。
你可以通过设置 `entrypoint` 选项为与根目录相关的的导入说明符（例如 `entrypoint: "/src/entrypoint"`）来扩展 Alpine。

这个文件的默认导出应该是一个函数，该函数接收一个在应用启动前的 Alpine 实例作为参数。这样做可以在高级用例中允许使用自定义指令、插件以及其他自定义功能。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import alpine from '@astrojs/alpinejs';
export default defineConfig({
  // ...
  integrations: [alpine({ entrypoint: '/src/entrypoint' })],
});
```



```js title="src/entrypoint.ts"
import type { Alpine } from 'alpinejs'
import intersect from '@alpinejs/intersect'
export default (Alpine: Alpine) => {
    Alpine.plugin(intersect)
}
```

## 使用

集成安装完成后，你可以在任何 Astro 组件中使用 [Alpine.js](https://alpinejs.dev/) 的指令和语法。Alpine.js 的脚本将会自动被添加到你的网站，并在每个页面上激活。你需要做的就是将插件脚本包含在页面的 `<head>` 部分。

以下示例将演示如何使用 [Alpine 的 Collapse 插件](https://alpinejs.dev/plugins/collapse) 来实现段落文本的展开和折叠功能：

```astro title="src/pages/index.astro" ins={6} ins="x-collapse"
---
---
<html>
	<head>
		<!-- ... -->
		<script defer src="https://cdn.jsdelivr.net/npm/@alpinejs/collapse@3.x.x/dist/cdn.min.js"></script>
	</head>
	<body>
    <!-- ... -->
		<div x-data="{ expanded: false }">
			<button @click="expanded = ! expanded">切换内容</button>
			<p id="foo" x-show="expanded" x-collapse>
        Lorem ipsum
			</p>
		</div>
	</body>
</html>
```

## TypeScript 的智能提示

`@astrojs/alpine` 集成会将 `Alpine` 对象添加到全局的 `window` 对象中。为了在你的开发环境中获得 `Alpine` 的自动完成提示，你需要在 `src/env.d.ts` 文件中添加如下代码：

```ts title="src/env.d.ts"
interface Window {
  Alpine: import('alpinejs').Alpine;
}
```

## 示例

* [Astro Alpine.js 示例](https://github.com/withastro/astro/tree/latest/examples/framework-alpine) 演示了如何在 Astro 项目中使用 Alpine.js。


[astro-integration]: /zh-cn/guides/integrations-guide/

[astro-ui-frameworks]: /zh-cn/guides/framework-components/#使用框架组件
